/*
 * Copyright 2002-2007 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.context;

import org.springframework.beans.BeansException;

/**
 * 如果一个对象，想要被其运行的 {@link ApplicationContext}通知，就需要实现这个接口。<br/>
 * Interface to be implemented by any object that wishes to be notified of the
 * {@link ApplicationContext} that it runs in. 。
 * 
 * <p>
 * Implementing this interface makes sense for example when an object requires
 * access to a set of collaborating beans. Note that configuration via bean
 * references is preferable to implementing this interface just for bean lookup
 * purposes.
 * 
 * <p>
 * This interface can also be implemented if an object needs access to file
 * resources, i.e. wants to call <code>getResource</code>, wants to publish an
 * application event, or requires access to the MessageSource. However, it is
 * preferable to implement the more specific {@link ResourceLoaderAware},
 * {@link ApplicationEventPublisherAware} or {@link MessageSourceAware}
 * interface in such a specific scenario.
 * 
 * <p>
 * Note that file resource dependencies can also be exposed as bean properties
 * of type {@link org.springframework.core.io.Resource}, populated via Strings
 * with automatic type conversion by the bean factory. This removes the need for
 * implementing any callback interface just for the purpose of accessing a
 * specific file resource.
 * 
 * <p>
 * {@link org.springframework.context.support.ApplicationObjectSupport} is a
 * convenience base class for application objects, implementing this interface.
 * 
 * <p>
 * For a list of all bean lifecycle methods, see the
 * {@link org.springframework.beans.factory.BeanFactory BeanFactory javadocs}.
 * 
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @see ResourceLoaderAware
 * @see ApplicationEventPublisherAware
 * @see MessageSourceAware
 * @see org.springframework.context.support.ApplicationObjectSupport
 * @see org.springframework.beans.factory.BeanFactoryAware
 */
public interface ApplicationContextAware {

	/**
	 * Set the ApplicationContext that this object runs in. Normally this call
	 * will be used to initialize the object.
	 * <p>
	 * Invoked after population of normal bean properties but before an init
	 * callback such as
	 * {@link org.springframework.beans.factory.InitializingBean#afterPropertiesSet()}
	 * or a custom init-method. Invoked after
	 * {@link ResourceLoaderAware#setResourceLoader},
	 * {@link ApplicationEventPublisherAware#setApplicationEventPublisher} and
	 * {@link MessageSourceAware}, if applicable.
	 * 
	 * @param applicationContext
	 *            the ApplicationContext object to be used by this object
	 * @throws ApplicationContextException
	 *             in case of context initialization errors
	 * @throws BeansException
	 *             if thrown by application context methods
	 * @see org.springframework.beans.factory.BeanInitializationException
	 */
	void setApplicationContext(ApplicationContext applicationContext)
			throws BeansException;

}
